<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Cloning and Copies : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Cloning and Copies
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Cloning and Copies</h1>

<p>
	You can clone an object to make it safe for manipulating.
	You can even clone an object in the middle of a query to run two different queries with similar settings!
</p>
<p>
	If you have an object that you want to duplicate in the database, creating a copy makes that very easy.
</p>

<h2 id="get_clone">Get Clone</h2>
<p>Get Clone returns a clone of the object.</p>

<p class="note"><strong>Note:</strong>&nbsp; PHP's clone function is only capable of performing a shallow clone of objects.  DataMapper's clone process has been improved over the default to be slightly less shallow, so related objects of a clone are also clones rather than references.</p>
<pre>
<samp>// Get a user
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_id</u></var><kbd>(</kbd><var>$id</var><kbd>);

</kbd><var>$clone </var><kbd>= </kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_clone</u></var><kbd>();</kbd>
</pre>

<p>Looking at the above, both the <var>$clone</var> and <var>$u</var> objects are identical except you can modify the data of one, without affecting the data stored in the other.  Saving the objects will of course update the same record in the database.</p>


<h2 id="get_copy">Get Copy</h2>

<p>Get Copy returns a copy of the object. This is essentially a clone of the object but with the ID cleared.  It can allow you to quickly save a new record of an existing similar item.  For example:</p>
<pre>
<samp>// Let's save a new hosting plan
</samp><var>$p </var><kbd>= new </kbd><var>Plan</var><kbd>();

</kbd><var>$p</var><kbd>-&gt;</kbd><var>name </var><kbd>= </kbd><dfn>'The 100GB Plan'</dfn><kbd>;
</kbd><var>$p</var><kbd>-&gt;</kbd><var>storage </var><kbd>= </kbd><var>1000</var><kbd>;
</kbd><var>$p</var><kbd>-&gt;</kbd><var>bandwidth </var><kbd>= </kbd><var>2000</var><kbd>;
</kbd><var>$p</var><kbd>-&gt;</kbd><var>databases </var><kbd>= </kbd><var>5</var><kbd>;
</kbd><var>$p</var><kbd>-&gt;</kbd><var>domains </var><kbd>= </kbd><var>5</var><kbd>;
</kbd><var>$p</var><kbd>-&gt;</kbd><var>emails </var><kbd>= </kbd><var>50</var><kbd>;

</kbd><var>$p</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>();

</kbd><samp>// Now, lets make a copy of that saved plan and base a new one off of it
</samp><var>$p </var><kbd>= </kbd><var>$p</var><kbd>-&gt;</kbd><var><u>get_copy</u></var><kbd>();

</kbd><samp>// Change only what we need to
</samp><var>$p</var><kbd>-&gt;</kbd><var>name </var><kbd>= </kbd><dfn>'The Big 150GB Plan'</dfn><kbd>;
</kbd><var>$p</var><kbd>-&gt;</kbd><var>storage </var><kbd>= </kbd><var>1500</var><kbd>;
</kbd><var>$p</var><kbd>-&gt;</kbd><var>bandwidth </var><kbd>= </kbd><var>2500</var><kbd>;

</kbd><samp>// And now save a new record
</samp><var>$p</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>();</kbd>
</pre>

<h1 id="Clone.DB">Database Object Cloning</h1>
<p class="note">Unless you've changed <var><i>$db_params</i></var> to be <dfn>FALSE</dfn>, you do not need to worry about this!</p>
<p>If you have <var><i>$db_params</i></var> set to <dfn>FALSE</dfn>, then the <var><i>$db</i></var> object is shared across all objects by default.</p>
<p>However, you can force the clone or copy to have an independent copy of the database object by passing <kbd>TRUE</kbd> to either method.</p>

<h4>Example:</h4>
<pre>
<var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>where_related</u></var><kbd>(</kbd><dfn>'group'</dfn><kbd>, </kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Administrators'</dfn><kbd>);

</kbd><var>$u2 </var><kbd>= </kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_clone</u></var><kbd>(</kbd><var><dfn>TRUE</dfn></var><kbd>); </kbd><samp>// force a clone of the DB object
</samp><var>$u2</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'id &lt;'</dfn><kbd>, </kbd><var>3</var><kbd>);

</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get</u></var><kbd>(); </kbd><samp>// contains all Admins
</samp><var>$u2</var><kbd>-&gt;</kbd><var><u>get</u></var><kbd>(); </kbd><samp>// contains only the Admins whose ID is less than 3</samp>
</pre>

</div>
<!-- END CONTENT -->


<div id="footer">
<p>
<span id="footer_previous">Previous Topic:&nbsp;&nbsp;<a href=""></a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;</span>
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>
<span id="footer_next">&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href=""></a></span>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
